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FOREWORD 


Two  of  the  most  important  elements  of  a computer  programming  effort 

are  documentation  and  program  debugging.  Documentation /is  often 

/ 

neglected  and  debugging  done  In  a random  manner.  In  or/der  to  avoid 

j 

these  pitfalls  in  the  programming  effort  of  Project  ABACUS,  a hand- 
book was  prepared  for  use  as  a guide  in  program  documentation  and 

debugging  efforts.  This  handbook  incorporates  the  pertinent  Army 

* / 

Regulations  and  on-the-job  experiences. 


ROBERT  G.  FOSTER 
(LTC,  SigC 
Program  Director,  Project  ABACUS 
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I.  INTRODUCTION 

This  manual  sets  forth  procedures  and  techniques  for  documenting,  modi- 
fying, and  debugging  the  application  and  system  programs  being  developed 
for  Project  ABACUS. 

II.  STANDARD  OPERATING  PROCEDURE  (SOP)  FOR  DOCUMENTATION 

A.  Purpose.  This  section  establishes  standards  and  provides  guid- 
ance for  preparing  documentation  of  computer  programs.  Documentation  of 
computer  programs  is  required  to: 

1.  Facilitate  program  use  and  maintenance. 

2.  Reduce  the  impact  of  personnel  changes. 

3.  Permit  flexibility  in  reassignment  of  programmers  to  meet 
unusual  workloads. 

4.  Contribute  to  the  exchange  of  programs  between  installations 
to  minimize  duplication  of  effort. 

5.  Facilitate  conversion  to  other  Automatic  Data  Processing 
Equipment  (ADPE). 

6.  Assist  In  audit  of  computer  processing. 

Documentation  is  often  known  as  the  "Achilles  Heel"  of  any  Data  Processing 
(DP)  dtoartment.  For  this  reason,  a continuous  update  of  documentation 
is  also  needed  to  prevent  lagging.  Changes  and  dates  of  revision  should 
be  maintained,  as  a programmer  or  analyst  is  likely  to  forget  the  intri- 
cacies and  vital  workings  of  a program  or  a procedure. 

B.  Computer  Program  Folder.  A computer  program  folder  will  be  es- 
tablished for  each  computer  program  prepared  for  operation.  Computer 
program  folders  will  be  prepared  in  accordance  with  standard  outline  and 
instructions  indicated  in  Appendix  J of  Army  Regulation,  AR  18-7,  Data 
Processing  Installation  Management,  Procedures,  and  Standards. 

Format  of  Outline: 

Chapter  1 - General 

1.  Identification 

2.  Description 

3.  Environment 


Ill  1.1  IUI*l«l|ll|ll 


Chapter  2 - Specifications 

1.  Purpose 

2.  Forms 


3.  Other  Information 


Chapter  3 - Program  Maintenance 

1.  Operating  Environment 

2.  Assumptions 

3.  Input 


4.  Output 

5.  Subroutines 

6.  Addenda 

Chapter  4 - Operating  Instructions 

1 . Genera  I 

2.  Input 

3.  Output 

4.  Setup 

5.  Termination 

6.  Addenda 

Exceptions  to  the  requirement  will  be  program  folders  covering  portions 
of  a real  time  system,  and  subsets  of  an  overall  program  system  may  deviate 
from  the  standard  outline,  as  appropriate,  due  to  their  uniqueness. 

C.  Source  Program  Documentation. 

1.  Document  as  much  of  the  program  within  the  code  as  possible 
by  extensive  use  of  meaningful  comment  notation  imbedded  within  the 
coding.  This  will  concentrate  the  documentation  where  it  will  do  the 
most  good.  If  the  documentation  remains  with  the  program,  comments  and 
code  maybe  modified  at  the  same  time.  All  comment  coding  will  start  with 
a blank  comment  line  and  end  with  a blank  comment  line. 
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2.  All  statement  numbers  will  be  sequential. 

3.  The  leading  information  that  must  be  present  at  the  beginning 
of  the  program  Is: 

C 

C Program  Name: 

C Written  By: 

C Date  Written: 

C Purpose: 

C Operational  Version: 

C 

4.  If  an  existing  program  is  being  modified  in  any  way,  the  name, 
date,  and  version  number  are  required  for  insertion  into  the  heading  coding. 
An  example  of  a heading  after  one  change: 

C 

C Program  Name: 

C Written  By: 

C Date  Written: 

C Purpose : 

C Operational  Version: 

C 

C Changed  By : 

C Date  Changed. 

C Reason  for  Change: 

C Operational  Version: 

C 

Example  of  heading  after  two  changes: 

C 

C Program  Name: 

C Written  By: 

C Date  Written: 

C Purpose: 

C Operational  Version: 

C 

C Changed  By: 

C Date  Changed : 

C Reason  for  Change: 

C Operational  Version: 

C 

C Changed  By: 

C Date  Changed: 

C Reason  for  Change: 

C Operational  Version: 

C 


5.  A record  of  changes  being  made  to  the  existing  programs  will 
be  maintained  In  detail,  to  Include: 


a.  The  reason  for  change. 

b.  Location  of  change. 


6.  A record  of  a I I files  and  the  authors  will  be  maintained  for 
identification  purposes,  to  include: 


a.  Author  Identification  (ID)  Number. 

b.  Device  Number. 

c.  Device  ID. 

d.  Name  of  FI le. 

e.  Length  of  File. 

f . Purpose  of  File. 

D.  Object  Program  Documentation. 


1.  Changes  will  be  made  to  the  source  code  and  recompiled.  No 
patches  will  be  made  to  an  object  program. 


2.  Only  one  version  of  an  object  program  will  be  kept  on  file. 


E.  Surtma ry . Good  documentation  can  be  summed  up  in  these  four  general 
ru I es : 


1.  Provide  adequate  documentation. 

2.  Document  within  program,  where  possible, 

3.  Be  considerate  of  the  next  programmer. 

4.  Be  neat. 
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PROGRAMMING  TECHNIQUES 


A.  Do  Loops  should  have  the  coding,  within  the  realm  of  the  loop, 
indented  three  spaces. 


Example:  DO  10  N = 1,23 

OUT(N)  = 0 
ICT  = ICT+N 
10  CONTINUE 


NOTE:  Always  use  a CONTINUE  statement  to  terminate  the  realm. 

B.  Statement  Labels. 


1.  Statement  labels  will  be  left  justified. 


2.  Reserve  specific  ranges  of  numbers  for  executable  statement 
labels  and  format  statement  label-s.  Example:  Reserve  1 through  999  for 

executable  statements  and  reserve  1000  and  above  for  format.  Labels  be- 
ginning with  99  would  be  reserved  for  termination  processing. 


C.  Variable  Name/Constant  Between  Two  Lines  of  Source  Code.  Never 


break  up  a variable  name  or  a constant  between  two  lines  of  source  code. 

D.  Statement  Continuations.  When  statements  are  continued  onto  a 


new  line,  indent  the  continuation  so  that  similar  parts  of  the  statement 
line  up.  Example:  2000  FORMAT  (1H0,  17,  F13.4  A1,  10X, 

17,  F14.7,  20X,  13) 


PROGRAMMING  CHECKLIST 
A . Program  Structure. 

1.  Is  the  organization  of  the  program  modular? 


2.  Does  each  routine  and  subroutine  perform  a well-defined, 
complete  function? 


3.  Is  the  program's  flow  straight  forward? 

4.  Does  it  go  from  top  to  bottom  instead  of  jumping  around? 
B.  Dialect. 


1.  Does  your  program  require  assembly  routines? 


2,  Are  there  assembly  routines  prepared  that  meet  your  needs 
and  do  not  contain  excess  functions? 
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C.  Program  Development. 


1.  Have  you  chosen  the  best  method  for  the  environment  in 
which  your  program  wit  I run? 

2.  Have  you  written  general  and  detailed  flowcharts? 

3.  Is  your  program  general  and  easy  to  interpret? 

4.  Can  it  be  used  easily  with  new  data? 

5.  Can  it  be  modified  easily? 

D.  Program  Documentation. 

1.  Has  AR  18-7  been  followed? 

2.  Are  the  program  headers  present  in  the  source  code? 

3.  Were  meaningful  comments  inserted  in  the  source  code? 

4.  Are  all  storage  locations,  that  are  used,  defined? 

5.  Were  the  outlined  tecnnigues  followed? 

V.  DEBUGGING  TECHNIQUES 

A.  I ntroduct ion . There  are  two  basic  approache  to  debugging: 

1.  Checking  the  program  before  feeding  it  into  the  computer. 

2.  Using  the  computer  to  detect  errors. 

Only  after  you  have  exhausted  the  process  of  checking  your  program  by  hand, 
should  you  resort  to  using  the  computer  to  find  any  remaining  errors. 

B.  Debugging  before  Compilation  or  Assembly. 

1.  After  drawing  up  the  flowcharts,  put  them  down  for  a period 
of  time.  Then  go  back  and  review  them  for  correctness. 

2.  Obtain  a listing  when  the  coding  is  finished  and  verify 
correctness  by  desk  checking.  A few  pointers  for  desk  checking: 

a.  Check  that  the  address  part  of  each  instruction  refers 
to  the  number  in  memory  (the  one  you  wish  to  make  reference  to).  To  aid 
the  checking,  you  should  keep  a careful  record  of  where  you  store  data, 
answers,  instructional  constants,  intermediate  answers,  etc.,  while  you 
are  writing  the  program. 


b.  Check  all  the  loops  you  have  written.  Things  to  chock 
for  In  your  loop: 


(1)  Is  the  correct  data  used  In  each  pass? 

(2)  Is  the  computer  sent  back  to  the  correct  place  on 
each  pass?  In  checking  this  point,  you  should  compare  your  program  care- 
fully with  the  flowchart. 

(3)  Will  the  computer  make  the  desired  number  of  passes 
through  the  loop? 

(4)  Is  there  an  exit  from  the  loop? 


(5) 


Is  there  a finite  limit  to  the  Iterations  In  the  loop? 


(6)  Instruction  modification  should  also  be  checked  care- 
fully in  your  loop. 

c.  Whenever  a program  sends  the  computer  to  a subroutine, 
you  should  check  the  calling  sequence  carefully. 

(1)  Each  subroutine  should  have  a write-up  describing  the 
required  calling  sequence. 

(2)  Be  sure  the  computer  is  sent  to  the  correct  subroutine. 

(3)  If  it  is  required  that  an  argument  be  in  the  accumulator 
when  the  computer  exits  to  a subroutine,  make  sure  you  prepare  your  program 
to  satisfy  this  requirement. 

(4)  If  the  subroutine  write-up  states  that  the  addresses  of 
the  arguments  should  be  included  In  the  calling  sequence,  be  sure  these 
addresses  are  placed  correctly  and  that  they  really  are  the  addresses  of 
the  arguments,  not  the  arguments  themselves. 

(5)  If  the  write-up  calls  for  an  error  return,  make  certain 
you  have  provided  one  in  your  program. 

d.  You  can  make  the  program  checking  process  easier  by 

> making  notes  on  the  coding  sheet  white  you  are  writing  your  program. 

e.  In  addition  to  checking  the  instructions  in  your  program, 

* make  certain  the  data  is  written  correctly. 

f.  To  make  checking  of  your  program  easier,  you  should  try 
to  relate  the  various  parts  of  the  program  to  the  corresponding  parts  of 
the  flowchart. 
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g.  When  you  have  checked  your  program  thoroughly  and  are 
absolutely  certain  it  contains  ro  errors;  when  a second  person  has  gone 
through  your  program  and  founj  no  mistakes;  when  you  are  convinced  that 
your  program  is  errorless,  then  you  may  test  It  on  the  computer  to  find 
out  whether  it  works.  It  is  just  possible  that  something  may  still  be 
wrong  with  your  program. 

3.  When  a new  copy  or  version  of  the  program  is  made,  either 
date  or  destroy  old  copies. 

C.  Debugging  and  Testing  after  Compilation  or  Assembly. 

1.  When  a new  listing  of  the  program  is  made,  either  date  or 
destroy  old  copies. 

2.  When  testing  a program,  the  following  principles  apply  to 
almost  any  processing  function: 

a.  Test  the  normal  cases. 

b.  Test  the  extremes. 

c.  Test  the  exceptions. 

D.  Summary.  We  have  taken  a look  at  some  of  the  philosophies  of 
program  testing  and  some  of  the  mechanical  aids  available.  If  we  wanted 
to  boil  everything  down  to  four  major  principles  of  testing,  they  would 
probably  be  the  following: 

1.  Write  the  initial  program  correctly. 

2.  Think  about  check-out  when  cod  trig. 

3.  Know  the  debugging  tools  which  are  available. 

4.  Make  the  program  prove  that  It  works. 

If  we  wished  to  express  these  principles  more  concisely,  we  might  state, 
"Be  a meticulous,  thoughtful,  well  informed  skeptic."  It  is  as  close 
as  you  can  come  to  a "magic  wand"  for  program  testing,  - and  ft  is  not 
too  close. 


